Описание различных видов включений

[( )] Текстовый блок

[= =] Преформатированный текст

[& &] Программный код

[% %] Формулы

[| |] таблицы

[/ /] Комментарии

[[ ]] Изображения

[` `] Ноты

Текстовый блок [( ... )]

Текстовое включение уже было описано в предыдущем пункте.

Преформатированный текст [= ... =]

Используется, если вы предварительно отформатировали текст как нужно (preformatted text) и хотите чтобы он никак не обрабатывался и не менялся при конвертации в другой формат. В преформатированном тексте применяется моноширинный шрифт. Всё тело блока отобразится «как есть». Включение обозначается квадратной скобкой и знаком = (равно).

В преформатированном тексте можно, например, разместить псевдографику:

[= Файловая схема
▒ Каждому своё
├── Каждому своё -- Валентин Пикуль.text
└──▒ images
	├── abcd.jpg
	└── efgh.png
=]

Классы преформатированного текста

text — зарезервированный класс для markvan-разметки. К такому тексту можно будет применять отдельное форматирование. Маркван-текст это не программный код, поэтому его демонстрируем через преформатированный текст.
? — quest — вопрос(задание, упражнение)
> — result — результат (выполнения кода или ответ к задаче или процесс решения)
!!! — danger — ошибка.
_ — hidden — скрытое

Программный код [& ... &]

Используется для размещения примеров кода. К нему может применяться подсветка команд и переменных (возможен запуск кода с выдачей результата с помощью отдельного сервиса).

Блок кода обозначается квадратной скобкой и знаком & (амперсанд).

[&
if x > 0 {
	a = х + b
}
&]

Классы программного кода

Класс включения используется для указания языка программирования.

[&python
n = 5
string = "Hello World "
print(string * n)  #Hello World Hello World Hello World Hello World Hello World
&]

n = 5
string = "Hello World "
print(string * n)  #Hello World Hello World Hello World Hello World Hello World

Формулы [% ... %]

Чтобы набирать формулы в обычном текстовом редакторе необходимо изучить один из языков разметки формул, например, AsciiMath, TEX, Math.

Включение формул обозначается квадратной скобкой и знаком % (процент). В классе указываете соответствующий тип включения:

asc, tex, math. В перспективе возможно создание маркван-нотации, для неё не нужно будет указывать класс.

AsciiMath

— это простой в написании язык разметки для математики (http://asciimath.org/).

Пример формулы в AsciiMath

[%asc
x = (-b +- sqrt(b^2 - 4ac))/(2a)
%]

Tex

— сложная система набора формул и даже текста целиком (https://en.wikipedia.org/wiki/TeX).

Пример формулы в TEX

[%tex
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
%]

Временная картинка результата AsciiMath и TEX (потом подключу скрипты)

MathMl

— язык разметки на основе XML для представления математических символов и формул в веб-документах (https://developer.mozilla.org/ru/docs/Web/MathML/Authoring).

Пример формулы в Math

[%math
<mi>x</mi> <mo>=</mo>
<mrow>
	<mfrac>
		<mrow>
		<mo>−</mo>
		<mi>b</mi>
		<mo>±</mo>
		<msqrt>
			<msup><mi>b</mi><mn>2</mn></msup>
			<mo>−</mo>
			<mn>4</mn><mi>a</mi><mi>c</mi>
		</msqrt>
		</mrow>
		<mrow> <mn>2</mn><mi>a</mi> </mrow>
	</mfrac>
</mrow>
%]

Результат в math

x = \frac{- b \pm \sqrt{b^{2} - 4 a c}}{2 a}

Комментарии [/ ... /]

Комментарии в тексте нужны для размещения заметок автора самому себе или соавторам. При конвертации в другие форматы комментарии могут быть скрыты в зависимости от настроек программы.

Блок комментариев обозначаются квадратной скобкой и знаком / (слеш).

[/
Это текст комментария - он не для читателя.
Я могу писать здесь сколько угодно строк.
/]

Классы комментариев

? — issue — открытый вопрос. Что-то незавершенное требующее решения, ещё не сформированное в виде задачи.
! — todo — сформулированная задача для исполнения в будущем. Из подобных комментариев можно автоматически составить список дел автора в произведении.

[/!
Перепроверить разметку комментариев по всему тексту перед публикацией!
/]

Таблицы [| ... |]

Таблицы можно рисовать в преформатированном включении символами либо псевдографикой.

Таблица 1. Покупки.

| Товар               | Цена, руб | Количество | Сумма, руб
|---------------------+-----------+------------+-----------
| Тетрадь ученическая | 100       | 2          | 200
| Карандаш простой    | 10        | 4          | 40
|---------------------+-----------+------------+-----------
| Итого                                        | 240

Cимволы, которые есть на клавиатуре

Таблица 1. Покупки.

┌─────────────────────┬───────────┬────────────┬────────────┐
│ Товар               │ Цена, руб │ Количество │ Сумма, руб │
├─────────────────────┼───────────┼────────────┼────────────┤
│ Тетрадь ученическая │ 100       │ 2          │ 200        │
│ Карандаш простой    │ 10        │ 4          │ 40         │
├─────────────────────┴───────────┴────────────┼────────────┤
│ Итого                                        │ 240        │
└──────────────────────────────────────────────┴────────────┘

Символы псевдографики

Минус такого подхода в том, что широкие таблицы могут не влезть в экран текстового редактора, а при переносе строк сложно воспринять их содержимое. К тому же, создание таблиц таким способом это очень долгий и трудоемкий процесс.

Маркван-разметка таблиц

Табличное включение обозначается квадратной скобкой и вертикальной чертой |.

Таблица отображается построчно, каждая ячейка в своей строке — так можно вместить в ячейку таблицы длинный текст или текст из нескольких строк.

Каждая ячейка сдвигается на два знака табуляция (так легче отслеживать столбцы). Двигаясь сверху вниз можно визуально сопоставить значения одного столбца разных ячеек.

[| Таблица 1. Покупки.
|Товар
		|Цена, руб
				|Количество
						|Сумма, руб
|Тетрадь ученическая в клеточку Арт 342135
		|100
				|2
						|200
|Карандаш простой H2 Koh-i-noor Арт 675631
		|10
				|4 м
						|40
|Итого
		|
				|
						|240
|]

Расширенные возможности таблиц

В маркван-разметке есть некоторые возможности по форматированию таблицы:

«шапка» таблицы для показа наименованй столбцов, отделяется строкой со знаками минус ---(минимум 3 символа).
«подвал» таблицы для показа итогов столбцов, отделяется строкой со знаками равно === (минимум 3 символа).
итоговый столбец, который образовался в результате вычисления других, помечается знаком равно = в заголовке столбца. При конвертации итоговые значения могут быть выделены жирным шрифтом или фоном. Также знак равно указывает на то, что это числовой столбец.
объединение ячеек в строке — вместо вертикальных линий ставится двоеточие :.
объединение ячеек в столбце — вместо вертикальных линий ставится точка . — это значит текущая ячейка несамостоятельная, а является продолжением верхней.
выравнивание цифр — знак больше > (больше) в заголовке таблицы указывает на то, что это числовой столбец, при конвертации его нужно выравнивать выравнивать по правому краю (кроме самого заголовка). Цифры желательно привести к единому формату.

[| Таблица 1. Покупки.
|Товар
		|Цена, руб
				:
						|>Количество
								|=Сумма, руб
.
		|>опт
				|>розница
						.
								.
------
|Тетрадь ученическая в клеточку Арт 342135
		|90.00
				|100
						|2
								|200
|Карандаш простой H2 Koh-i-noor Арт 675631
		|8.50
				|10
						|4
								|40
======
|Итого:
		:
				:
						:
								|240
|]

И вот как выглядит таблица в браузере после конвертации:

я таблица

Медиа-включения и файлы [[ ... ]]

Часто требуется вставить в повествование: рисунки, фотографии, диаграммы, схемы, графики и т.д. Соответственно, нам нужно вставить ссылку на изображение в виде файла, например, в формате png, svg или jpg.

Медиаконтент размещается в тексте посредством включения из двойных квадратных скобок. В теле включения располагается ссылка указывающая на место расположения исходного файла.

В данном примере изображение находится прямо в той же папке, где лежит текстовый файл.

[[ 
>duma20_cover.jpg
]]

Другие пути расположения файлов рассмотрены в разделе про ссылки.

Описание изображения

По названию файла не всегда понятно что это за изображение (особенно для стороннего читателя), поэтому лучше добавлять описание того, что в этом файле.^*

[[
>/img/duma20_cover.jpg (Обложка книги 20 лет спустя Александра Дюма)
]]

^* При конвертации в html описание вставится в атрибуты title и alt.

Название

Так же как у текстовых блоков или других включений, у медиа-включения может быть название и описание.

[[ Двадцать лет спустя.
>/img/duma20_cover.jpg
]] Историко-приключенческий роман французского писателя Александра Дюма.

Двадцать лет спустя. Историко-приключенческий роман французского писателя Александра Дюма.

Далее по медиа не утверждено

Размер

Мультиизображения или альтернативные пути??

Аудио

[[audio Пример мелодии
/audio/korotkaya-melodiya.mp3
]] Автор или пояснение

В видео и аудио можно указывать одно и то же произведение в разных форматах.

Видео

[[video
/video/Водопад.mov
]]

Видео в html-фрейме

Часто видео располагается не в этой же папке на компьютере пользователя, а на видеосервере, который предоставляет и свой проигрыватель. Поэтому в специальное медиа-включение класса frame вставляется код из видеохостинга

[[iframe
<iframe width="1120" height="630" src="https://www.youtube.com/embed/4bHUsy74Fss" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
]]

Указание нескольких исходников

В аудио и видео-включениях можно указывать несколько видов исходников, чтобы проигрыватель мог выбрать тот, который он сможет воспроизвести.

[[audio
/audio/korotkaya-melodiya.mp3
/audio/korotkaya-melodiya.ogg
]]

В изображениях тоже можно указывать несколько исходников. Но следует понимать, что будет использоваться только первое.

Ноты [` ... `]

Для отображения нот необходим используем квадратную скобку и апостроф `. На текущий момент можно использовать включение с соответствующим классом abcnota. Abc notation — текстовая нотная система для народной и традиционной музыки (https://abcnotation.com/). Возможно в будущем появится маркван-разметка для нот, тогда не нужно будет указывать класс.

из https://www.abcjs.net/#what

[`abcnota
X: 1
T: Cooley's
M: 4/4
L: 1/8
K: Emin
|:D2|"Em"EBBA B2 EB|\
	~B2 AB dBAG|\
    "D"FDAD BDAD|\
    FDAD dAFD|
"Em"EBBA B2 EB|\
    B2 AB defg|\
    "D"afe^c dBAF|\
    "Em"DEFD E2:|
|:gf|"Em"eB B2 efge|\
    eB B2 gedB|\
    "D"A2 FA DAFA|\
    A2 FA defg|
"Em"eB B2 eBgB|\
    eB B2 defg|\
    "D"afe^c dBAF|\
    "Em"DEFD E2:|
`]

Пока не установлен яваскрипт для обработки включения, можно посмотреть на результат конвертации в виде картинки:

Далее не утверждено

Оглавление [§ ... §]

Оглавление создаётся автоматически при конвертации исходника в другой формат. Для научного/справочного произведения оглавление располагается в начале, после аннотации, то есть перед началом самого произведения. Для художественной литературы оглавление следует расположить в конце, чтобы преждевременно не раскрывать читателю содержание произведения.

Блок оглавления это тоже включение со знаком § (параграф). По умолчанию, оглавление будет находится в конце. Но вы можете при создании текстового документа расположить пустое включение оглавления в нужном вам месте.

[§ Оглавление
§]

Можно указать оглавление сразу и ограничить необходимую глубину вложения, указав в качестве класса тип заголовка, которым следует ограничиться.

[§- Оглавление
§]

Вы можете заполнить огравление заголовками для удобства чтения исходника, но содержимое оглавления при экспорте всё-равно перезапишется на те заголовки, которые указаны в тексте.

Псевдо-включение [{ ... }]

Раздел включений содержит довольно много информации.Тем не менее, это ещё не всё. Далее будут рассматриваться композиции включений и специфика их применения в решении различных практических задач.

посвящен отдельный раздел.